Integration Guide Kawasaki LS

Note: We strongly recommend that you read the Robot communication overview before this integration guide.

This guide describes the Robot module 1.5.0 for Kawasaki robots. Use it with Locator Studio (LS) 1.5.

Contents

• 1 Prerequisites

• 2 Robot controller setup

  • 2.1 Controller configuration

    • 2.1.1 Network configuration

  • 2.2 Robot module installation

    • 2.2.1 Loading the Robot module files

• 3 Robot module

  • 3.1 Robotic API

    • 3.1.1 Connection procedures

    • 3.1.2 Communication procedures

    • 3.1.3 Info data

    • 3.1.4 Global variables

    • 3.1.5 Error codes

  • 3.2 Example programs

    • 3.2.1 Main program example

    • 3.2.2 Calibration example

  • 3.3 Error handling

• 4 Running the Main program example

  • 4.1 Prerequisites

  • 4.2 Reteaching the robot poses

  • 4.3 Runtime

• 5 Troubleshooting

• 6 Version and brand ID

• 7 Migration

1 Prerequisites

• Kawasaki E-series or F-series robot controller.

• The controller must support the AS TCP/IP socket instructions (TCP_CONNECT, TCP_SEND, TCP_RECV).

• A PC with KRTerm (or a USB stick) to load the .pg files.

• Locator Studio 1.5 on the vision controller.

See the Robot module support matrix for the supported features.

2 Robot controller setup

2.1 Controller configuration

2.1.1 Network configuration

Turn on the robot controller and wait for the system to boot. Open the Menu screen and select the Aux Function option:

In the Aux function menu, select System and Network Settings:

The robot controller has two Ethernet ports. Use Port 1 for communication with Locator Studio. Use Port 2 to transfer programs between the PC and the robot controller with KRTerm.

Configure Port 1 for your network. Make sure that the robot controller and the vision controller with Locator Studio are on the same subnet.

Configure Port 2 to transfer programs between the PC and the robot controller. Click Next Page, configure the network settings and click the Enter button to confirm.

Restart the robot controller to apply the network settings.

The robot program connects to the vision controller on port 11003. The LS Robot module has no Robot State Server. For hand-eye scans and calibration, the robot sends its pose together with the request.

2.2 Robot module installation

2.2.1 Loading the Robot module files

The Robot module is shipped as Photoneo_LS_Module_1_5_0.zip. It contains:

File	Content
AS/photoneo_locator.pg	The whole module: connection, request and receiving programs and constants (init_consts). Do not edit.
AS/example_programs/*.pg	13 example programs, see Example programs.
README.md, CHANGELOG.md	Short description and version history.
Kawasaki LS 1.4.0 Cheat Sheet [v_04_2026].xlsx	Quick reference (written for module 1.4).

Load photoneo_locator.pg first, then the example program you want to use (for example locator_example.pg).

You can copy the .pg files to the robot controller directly from a USB stick with the teach pendant. The easiest way, however, is to use the KRTerm tool (download_1, download_2).

Make sure that Port 2 is configured for communication with your PC and that both devices are on the same subnet. You must be able to ping the robot controller from the command line.

Open KRTerm and select COM -> Options to add a new robot controller:

Enter the IP address of Port 2 that you configured on the teach pendant in the previous step. Click the Add button:

Click File -> Set Current Folder and select the folder with the extracted .pg files:

You can now connect to the robot. Make sure that you can ping the robot controller from your PC, then click the Connect button.

If the connection is successful, you see the login prompt shown in the figure below:

The login name is as. After a successful login, you can send commands directly to the robot controller.

To load .pg files to the robot controller, enter the LOAD command, for example:

LOAD photoneo_locator.pg
LOAD locator_example.pg

Make sure that all files loaded successfully.

The robot controller is now configured to work with Locator Studio.

3 Robot module

The Robot module is easy to integrate into existing applications written in the AS language. Your program calls the AS programs (procedures) described below with CALL.

3.1 Robotic API

Note: See Action requests for what each request does on the vision controller side.

3.1.1 Connection procedures

Warning: These procedures are part of photoneo_locator.pg and must not be edited!

Procedure	Description / Usage
connect_to_vc(.ret_val_conn)	Calls init_consts, closes a socket left open, connects to the vision controller and sends the brand ID. Set before the call (global variables): vc_ip[1] .. vc_ip[4] - IP address of the vision controller, bp_port - port, use 11003. Set in init_consts (adjust if needed): connect_att - number of connection attempts (default 5, -1 = try forever), tout_open - timeout of one attempt (60 s), tout_recv / tout_send - receive / send timeout (60 s). .ret_val_conn - result (0 = connected). Call it once at the start of the program. vc_ip[1] = 192 vc_ip[2] = 168 vc_ip[3] = 0 vc_ip[4] = 80 bp_port = 11003 CALL connect_to_vc (ret_val)
close_socket()	Closes the connection to the vision controller. connect_to_vc calls it automatically if a previous connection is still open. Call it at the end of your program. You can also call it manually if a socket is still open (see Troubleshooting).

3.1.2 Communication procedures

Warning: These procedures are part of photoneo_locator.pg and must not be edited!

• vision_system_i - global variable with the vision system ID. Set it before every request that needs a vision system (marked VS below).

• .ret_val... - the first parameter of each procedure. It receives the result (error code, 0 = OK). The global variable error_msg also stores the same value.

• .&tcp_pose - the robot TCP pose as a transformation (POINT), for example from HERE .tcp. Pass it as .&tcp.

• Only one request can be open at a time. Asynchronous requests (Scan, Trigger scan, Localize on the last scan) only send the request. Receive the response with the matching receiving procedure before you send the next request.

Locator requests

Procedure	ID	Inputs	Outputs
req_scan(.ret_val_scan)	19	VS (cell-mounted sensor)	send result; receive the response with wait_for_scan
req_scan_tcp(.ret_val_scan, .&tcp_pose)	19	VS, TCP pose (hand-eye sensor)	send result; receive the response with wait_for_scan
wait_for_scan(.ret_val_wait)	-	-	result of the Scan request
req_objects(.ret_val_pose, .requested_num)	20	VS, number of poses wanted	error code, pho_obj_poses[1..num_of_objects], num_of_objects, Info data
req_all_objects(.ret_val_pose)	20	VS (asks for all objects)	same as req_objects
req_single_obj(.ret_val_pose)	20	VS (asks for one object)	same as req_objects, plus the pose in pho_obj_pose
req_get_status(.ret_val_status)	22	VS	error code, num_localized, num_ready, process_state
req_trigger_scan(.ret_val, .&tcp_pose)	30	VS, TCP pose (hand-eye sensor; leave it out for a cell-mounted sensor)	send result; receive the response with wait_for_req_comp
req_reuse_scan(.ret_val, .&tcp_pose)	31	VS, TCP pose (hand-eye sensor; leave it out for a cell-mounted sensor)	send result; receive the response with wait_for_req_comp
req_change_bbox(.ret_val, .bbox_id)	33	VS, bounding box ID	error code
wait_for_req_comp(.ret_val)	-	-	result of the open request (any request). Returns 0 immediately if no request is open.

Calibration requests

Procedure	ID	Inputs	Outputs
req_add_point(.ret_val_add, .&tcp_pose)	5	TCP pose at the calibration point	error code
req_calib_start(.ret_val_start, .solution_id, .vs_id)	25	solution ID, vision system ID	error code
req_calib_stop(.ret_val_stop)	26	-	error code
req_calib_save(.ret_val_save)	27	-	error code, camera_pose, calib_acc

Solution requests

Procedure	ID	Inputs	Outputs
change_sol_req(.ret_val_sol, .solution_id)	9	solution ID	error code
start_sol_req(.ret_val_sol, .solution_id)	10	solution ID	error code
stop_sol_req(.ret_val_sol)	11	-	error code
get_run_sol_req(.ret_val_sol)	12	-	error code, running_sol_id

Other requests

Procedure	ID	Inputs	Outputs
req_comm_check(.ret_val)	100	-	error code

3.1.3 Info data

The module stores the values returned by the requests in global variables. See Info data for the meaning of each key and the request that returns it. init_consts resets the values at every connect_to_vc. Every Get objects response resets num_of_objects, max_height and angle.

The per-object values (keys 4-6) use the same index as pho_obj_poses: dimensions_x[n] belongs to pho_obj_poses[n] (first object = 1).

Key	Variable	Unit in robot	Returned by
4	dimensions_x[n]	mm	Get objects
5	dimensions_y[n]	mm	Get objects
6	dimensions_rot[n]	rad	Get objects
7	nn_label	index	Get objects
8	max_height	mm	Get objects
9	angle	rad	Get objects
10	calib_acc	µm	req_calib_save
11	running_sol_id	ID	get_run_sol_req
12	num_localized	count	req_get_status
13	num_ready	count	req_get_status
14	process_state	1 / 0	req_get_status
pose	pho_obj_poses[n], pho_obj_pose	POINT (TRANS: X, Y, Z in mm, O, A, T in deg)	Get objects
pose	camera_pose	POINT (TRANS: X, Y, Z in mm, O, A, T in deg)	req_calib_save

3.1.4 Global variables

Besides the Info data variables, the module uses these global variables:

Variable	Meaning
vc_ip[1..4], bp_port	IP address and port of the vision controller. Set by your program.
vision_system_i	Vision system ID used by the next request. Set by your program.
num_of_objects	Number of object poses received by the last Get objects request.
error_msg	Result of the last procedure (same value as .ret_val...).
active_req_id	ID of the request waiting for a response (-1 = none).
connect_att, tout_open, tout_recv, tout_send	Connection attempts and timeouts in seconds (set in init_consts).
sock_closed_rc	TRUE when the socket is closed.

3.1.5 Error codes

init_consts defines these error code constants. See Error codes for their meaning and troubleshooting. Other codes are returned as numbers.

AS constant	Code	AS constant	Code
ok	0	invalid_vs	460
service_err	1	calib_running	461
unknown_req	2	calib_not_running	462
comm_failure	3	calib_stop_err	463
bad_data	4	calib_start_err	464
timeout	5	calib_disabled	465
invalid_sol	450	calib_not_enough_points	466
another_sol	451	calib_not_enough_angles (calibration accuracy above the allowed threshold)	467
sol_start_err	452	scanner_not_available	468
sol_not_run	453	calib_forbidden	469
sol_stop_err	454	vs_not_found	500
sol_incomplete	455	empty_scene	501
invalid_brand	457	no_obj_run	502
sol_running	458	no_obj_stop	503
sol_forbidden	459	reject_run	504
-	-	reject_stop	505

3.2 Example programs

The folder AS/example_programs contains these programs. Each one sets vc_ip / bp_port, connects and shows one feature. The error handling in the examples is only a demonstration - adapt it to your application.

File (AS program)	Purpose
locator_example.pg	Basic loop: scan, get 3 object poses and pick them. Listing below.
multiple_vision_systems.pg	Two vision systems that alternate in every cycle.
change_solution.pg	Picks with solution 1, switches to solution 2 (change_sol_req) and then back.
change_bbox.pg (program change_bbox_example)	Switches the active bounding box (req_change_bbox) and scans.
get_status.pg	Reads the vision system status (req_get_status) around a scan.
hand_eye.pg	Sensor on the robot: scans with the TCP pose (req_scan_tcp).
multiview_static.pg	Hand-eye MultiView: trigger scans at 3 fixed poses (req_trigger_scan), then req_scan.
multiview_dynamic.pg	Hand-eye MultiView: trigger scans along a CP ON path through 7 waypoints, then req_scan.
trigger_scan.pg (program trigger_scan_example)	Minimal Trigger scan example with wait_for_req_comp.
reuse_scan.pg	Vision system 1 scans, vision system 2 localizes on the same scan (req_reuse_scan).
comm_check.pg (program comm_check_example)	Sends a Communication check request (req_comm_check).
calibration.pg	Adds 9 calibration points (req_add_point). Start and save the calibration in Locator Studio.
calibration_expert.pg	9-point calibration with pose check. With calib_auto = TRUE it also sends start, save and stop.

3.2.1 Main program example

This program is a very basic example of a locator application that picks objects from a tray.

It connects to the vision controller. Then, in a loop, it:

• moves to a scanning pose and requests a scan,

• moves to a starting pose above the tray and requests a specific number of object poses,

• if no error occurred, picks the reported objects in a loop:

  • moves to an approach pose above the object,

  • moves in a linear path to the object and picks it (you must add the gripper command here),

  • moves in a linear path to a depart pose above the object,

  • runs the placing procedure (you must implement it).

Name: locator_example.pg (folder example_programs)

.PROGRAM locator_example () ;
  ; *******************************************************************
  ;
  ; Program:      locator_example
  ; Comment:      Main program template with single vision system
  ; Author:       Photoneo s.r.o.
  ;
  ; Date:         20/10/2022
  ;
  ; *******************************************************************
  ;
  ;// Amend the Network settings - IP address of the Action request server (Robot interface)
  vc_ip[1] = 192
  vc_ip[2] = 168
  vc_ip[3] = 0
  vc_ip[4] = 80
  ;// Amend the Network settings - Action request server port (unrecommended)
  bp_port = 11003
  ;// Connect to the Vision Controller
  CALL connect_to_vc (ret_val)
  ;// Check return value, abort in case of failure
  IF (ret_val <> 0) THEN
    GOTO quit
  END
  ;// Set Vision System ID
  vision_system_i = 1
  SPEED 10 ALWAYS
  ;// MAIN LOOP
  WHILE (TRUE) DO
    ;// Move to Scanning pose in which the robot does not occlude the scanning area
    JMOVE #scanning_pose
    BREAK
    ;// Request scan acquisition
    CALL req_scan(ret_val)
    ;// Receive response from the scan request
    CALL wait_for_scan (ret_val)
    ;// Check return value, abort in case of failure
    IF (ret_val <> 0) THEN
      GOTO quit
    END
    ;// Move to Starting pose
    JMOVE #starting_pose
    ;// Request exact number of object poses
    .requested_num = 3
    CALL req_objects (ret_val, .requested_num)
    ;// Check return value, abort in case of failure
    IF (ret_val <> 0) THEN
      GOTO quit
    END
    ;// Pick all reported objects in loop
    FOR .i = 1 TO num_of_objects STEP 1
      ;// Move to Approach
      JAPPRO pho_obj_poses[.i], 100
      ;// Move to the reported object pose
      LMOVE pho_obj_poses[.i]
      BREAK
      ;// Activate gripper here
      ;// Move to Depart
      LDEPART 100
      ;// Execute placing here
    END
  END
  ;// End of the MAIN LOOP
quit:
  ;// Disconnect from the Vision Controller
  CALL close_socket
.END

3.2.2 Calibration example

calibration.pg is a template for semi-automatic calibration. Before you run it:

• teach #calib_start (the pose that the robot passes between the calibration poses) and #calib_1 .. #calib_9,

• start the calibration in Locator Studio.

For each of the 9 poses, the program does JMOVE #calib_N, BREAK, HERE .tcp and req_add_point(ret_val, .&tcp), then returns to #calib_start. On an error, it stops. When all points are added, check and save the result in Locator Studio.

calibration_expert.pg runs the full calibration from the robot. It first stops (HALT) at #default_pose so that you can confirm the poses. It also checks that no pose still has its default value. With calib_auto = TRUE, it does these steps:

1. req_calib_start(ret_val, sol_id, vision_system_i) - starts the calibration.

2. For each of the 9 poses: move, HERE .tcp, req_add_point(ret_val, .&tcp).

3. req_calib_save(ret_val) - saves the result; camera_pose and calib_acc are filled.

4. req_calib_stop(ret_val) - ends the calibration.

Run both programs step by step in MANUAL mode and check that the robot does not collide between the poses.

3.3 Error handling

Every request procedure returns its result in .ret_val... and in error_msg. Check the result after each synchronous request and after each receiving procedure (wait_for_scan, wait_for_req_comp). See Error codes for the list of codes.

What the module does when a problem occurs:

• Connection fails - connect_to_vc tries connect_att times and returns 3 (communication error).

• No data within the timeout (tout_recv / tout_send, 60 s) - the procedure returns 5 (timeout). Other socket errors return 3. After 3 or 5, the request stays open. Call connect_to_vc again to reconnect.

• Logic errors - the module prints a message, closes the socket and stops the program (HALT). This happens when:

  • a request is sent before the previous response was received,

  • wait_for_scan is called without a Scan request,

  • the response does not match the request.

• Messages - the module prints messages with the prefix LOC_CLIENT:. You can see them on the teach pendant under Menu -> Keyboard.

4 Running the Main program example

4.1 Prerequisites

Before you run the Main program example, make sure that:

• a fully configured solution with a single vision system is ready for deployment,

• the robot controller is configured as described in the chapter Robot controller setup of this integration guide,

• the Locator Studio network settings are configured,

• the gripper commands are added to the program (optional - without them, the robot does not actually pick the object),

• the placing procedure is implemented.

4.2 Reteaching the robot poses

The Main program example uses the following poses (joint values):

• #scanning_pose - the robot requests the scan in this pose. For a cell-mounted sensor, the robot must not occlude the scanning area in this pose. For a hand-eye sensor, use req_scan_tcp instead (see hand_eye.pg).

• #starting_pose - the robot moves from this pose to a pose above the reported object pose (an approach pose).

Also set vc_ip[1..4] to the IP address of the vision controller, and implement the gripper commands and the placing.

4.3 Runtime

Deploy your solution. The Action Request Client status on the Deployment page must be DISCONNECTED (from the Action Request Server).

First, select the program to run. Click the yellow program rectangle on the teach pendant touch screen:

Select Directory to open the program list:

Find and select the locator_example program:

When the program is ready, hold the A key and press the RUN/HOLD key on the teach pendant. The RUN status appears in the top right corner:

Turn on the motor power: hold the A key and press the MOTOR_ON/JOG key. You hear the motor brakes release, and the MOTOR status appears next to the RUN status in the top right corner.

Start the program on the robot controller: hold the A key and press the CYCLE START/CONT key. The CYCLE status turns green in the top right corner:

The Action Request Client status on the Deployment page changes to CONNECTED.

Press Menu -> Keyboard on the teach pendant to see the LOC_CLIENT: messages of the Robot module.

When the robot receives the object poses, it starts to move.

NOTE: Be ready to stop the robot motion immediately. We strongly recommend that you reduce the speed to 10% of the maximum during the first tests.

5 Troubleshooting

If you see the Open Socket Error shown in the figure below, the previous connection to the Action Request Server was not closed correctly.

Run the close_socket() program to close the previous session correctly:

6 Version and brand ID

• Robot module version: 1.5.0

• Brand ID (sent after connecting): KAWASAKI/L/1.5.0XXXXXXXX

7 Migration

To update the module, remove the old module programs, load the new photoneo_locator.pg and check your main program against the changes below.

• 1.4 -> 1.5: New brand ID. Each Info data message now carries one value, and the module stores it by its key. New variable nn_label. Main programs written for 1.4 still work.

See the general migration guide 1.4.x -> 1.5.x for details.